Skip to content

Add nullable enum guidance: null vs none sentinel values#586

Open
OlgaPodo wants to merge 1 commit into
microsoft:vNextfrom
OlgaPodo:guideline-update/nullable-enums
Open

Add nullable enum guidance: null vs none sentinel values#586
OlgaPodo wants to merge 1 commit into
microsoft:vNextfrom
OlgaPodo:guideline-update/nullable-enums

Conversation

@OlgaPodo
Copy link
Copy Markdown
Collaborator

Summary

Add a new 'Nullable enums' section to graph/patterns/enums.md with guidance on when to use null vs a none sentinel member for enum properties.

The existing page mentions that 'a nullable enum can very likely be avoided by adding a none member' but does not explain:

  • When null is the right choice vs none
  • The anti-pattern of combining both
  • Decision criteria for API designers

Changes

New #### Nullable enums section added after 'Enum or Booleans', containing:

  • null vs none comparison table — clarifies the semantic difference
  • Note on unknownFutureValue — reinforces that it is always required and unrelated to nullability
  • Prefer none over nullable — recommended pattern with CSDL example
  • When nullable is appropriate — three criteria that must all apply
  • Anti-pattern: nullable + none — warns against combining both with example

Context

Identified as a guideline gap during Graph API review discussions.

@OlgaPodo OlgaPodo requested a review from a team as a code owner May 12, 2026 00:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant